package com.itheima.behavior.service;

import com.itheima.model.behavior.dtos.RankingQueryDto;
import com.itheima.model.common.dtos.ResponseResult;

/**
 * 排行榜服务接口
 */
public interface RankingService {

    // ========== 实时排行榜（Kafka Streams 计算）==========
    
    /**
     * 获取实时热度排行榜（反映当前正在发生的热点）
     * @param limit 返回数量
     * @return 排行榜列表
     */
    ResponseResult getRealtimeHotRanking(Integer limit);

    // ========== 综合排行榜（定时任务计算，带时间衰减）==========
    
    /**
     * 获取图书热度排行榜（历史累积+时间衰减）
     * @param limit 返回数量
     * @param timeRange 时间范围
     * @return 排行榜列表
     */
    ResponseResult getBookHotRanking(Integer limit, String timeRange);

    /**
     * 获取图书阅读排行榜
     * @param limit 返回数量
     * @param timeRange 时间范围
     * @return 排行榜列表
     */
    ResponseResult getBookReadRanking(Integer limit, String timeRange);

    /**
     * 获取图书收藏排行榜
     * @param limit 返回数量
     * @param timeRange 时间范围
     * @return 排行榜列表
     */
    ResponseResult getBookCollectRanking(Integer limit, String timeRange);

    /**
     * 获取图书点赞排行榜
     * @param limit 返回数量
     * @param timeRange 时间范围
     * @return 排行榜列表
     */
    ResponseResult getBookLikeRanking(Integer limit, String timeRange);

    /**
     * 获取用户阅读时长排行榜
     * @param limit 返回数量
     * @param timeRange 时间范围
     * @return 排行榜列表
     */
    ResponseResult getUserReadingTimeRanking(Integer limit, String timeRange);

    /**
     * 获取用户活跃度排行榜
     * @param limit 返回数量
     * @param timeRange 时间范围
     * @return 排行榜列表
     */
    ResponseResult getUserActiveRanking(Integer limit, String timeRange);

    /**
     * 通用排行榜查询
     * @param dto 查询参数
     * @return 排行榜列表
     */
    ResponseResult getRanking(RankingQueryDto dto);

    /**
     * 获取用户在排行榜中的排名
     * @param userId 用户ID
     * @param rankingType 排行榜类型
     * @return 排名信息
     */
    ResponseResult getUserRank(Integer userId, String rankingType);

    /**
     * 获取图书在排行榜中的排名
     * @param bookId 图书ID
     * @param rankingType 排行榜类型
     * @return 排名信息
     */
    ResponseResult getBookRank(Integer bookId, String rankingType);

    // ========== 笔记排行榜 ==========
    
    /**
     * 获取实时热门笔记排行榜
     * @param limit 返回数量
     * @return 排行榜列表
     */
    ResponseResult getRealtimeHotNotes(Integer limit);

    /**
     * 获取综合热门笔记排行榜
     * @param limit 返回数量
     * @return 排行榜列表
     */
    ResponseResult getHotNotes(Integer limit);

    // ========== 书评排行榜 ==========
    
    /**
     * 获取实时热门书评排行榜
     * @param limit 返回数量
     * @return 排行榜列表
     */
    ResponseResult getRealtimeHotReviews(Integer limit);

    /**
     * 获取综合热门书评排行榜
     * @param limit 返回数量
     * @return 排行榜列表
     */
    ResponseResult getHotReviews(Integer limit);

    /**
     * 获取指定图书的热门笔记
     * @param bookId 图书ID
     * @param limit 返回数量
     * @return 笔记列表
     */
    ResponseResult getBookHotNotes(Integer bookId, Integer limit);

    /**
     * 获取指定图书的热门书评
     * @param bookId 图书ID
     * @param limit 返回数量
     * @return 书评列表
     */
    ResponseResult getBookHotReviews(Integer bookId, Integer limit);
}

